<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html version="4.01"><head><title>[retawq] Run-Time Configuration
Options</title></head>
<body text="#000000" bgcolor="#cccccc" link="#0000ff" vlink="#551a8b"
alink="#551a8b" lang="en">
<center><b><font size="+2">retawq Documentation</font><br><font
size="+1">Run-Time Configuration Options</font></b></center>

<p><a name="intro"></a><b>Introduction</b></p>

<p>When retawq starts, it tries to get its run-time configuration from up to
two places, in this order:</p>
<ul>
<li>A "built-in" configuration; cf. the <a href="ctconfig.html">compile-time
configuration option</a> OPTION_BIRTCFG. This is a rather special possibility,
intended for users with rare needs.</li>
<li>An "external" configuration file which is normally located at
"/home/<i>your_home</i>/.retawq/config", depending on the environment variable
"HOME". (You can make retawq use a different directory with the <a
href="arg.html">command-line option</a> "--userdir=<i>path</i>".)</li>
</ul>

<p>Each run-time configuration (built-in or file) consists of text lines which
represent sections and subsections:</p>

<p><ul>
<li>The beginning of a section is marked by a line which starts with a
non-whitespace character. (Space and tabulator characters are
"whitespace".)</li>
<li>A subsection ("rule") within a section simply is a single line which starts
with a whitespace character. When applied, rules are tested in the given order
until a matching rule (e.g. a rule containing a matching host name pattern) is
found; if no rules are given or none of the given rules matches, retawq's
internal default rule applies. - Some sections can't have subsections, simply
because they don't need any...</li>
<li>Lines which begin with a "#" are comment lines and ignored by retawq.</li>
</ul></p>

<p>There's a <a href="example-config">configuration example</a> available. The
below information shows which sections can be specified and how subsections are
interpreted; if something is not explicitly configured, an implicit default
behavior is applied. Please note that case matters for all option names: don't
use uppercase letters where lowercase letters are required.</p>

<p><a name="optui"></a><b>Options Part I: User Interface</b></p>

<p><ul>

<li><b>bookmarks</b> - the <a href="scheme.html">URL</a> of a bookmarks
document which shall be displayed when you use the <a href="key.html">keyboard
command</a> "b"</li>

<li><b>colors</b> - By default, retawq displays colored text on any text
terminal which supports colors, and it mostly uses white color on a black
background. If you don't like colors at all, use "colors off". If you want to
get black-on-white text, use "colors reverse".</li>

<li><b>dont-confirm</b> - Normally retawq asks you for confirmation if you try
to perform a command which may have "dangerous" or unwanted effects, e.g.
quitting the program or overwriting a file. If you know the program so good
that you don't handle it the wrong way, you can disable the enervating :-)
questions individually with the following keywords:
<ul>
<li><i>quit</i> - don't ask when quitting retawq (keyboard command "Q")</li>
<li><i>close</i> - don't ask when closing a window (keyboard command "C")</li>
<li><i>overwrite</i> - don't ask before overwriting a local file</li>
<li><i>form-submit</i> - don't ask before submitting an HTML form to an HTTP
server</li>
<li><i>form-reset</i> - don't ask before resetting an HTML form, i.e. setting
all elements of a form back to their default values</li>
<li><i>form-repost</i> - don't ask before re-submitting an HTML form to an HTTP
server using the "post" method; this method is often used for tasks like adding
a record to a database, and adding it twice normally isn't a good idea; a
re-submit can e.g. happen if you reload a document which resulted from a "post"
operation.</li>
<li><i>enforce-html</i> - don't ask before enforcing the interpretation of a
document as HTML source code (keyboard command "H")</li>
<li><i>enable</i> - don't ask before enabling a disabled HTML form element
(keyboard command "E")</li>
</ul></li>

<li><b>execext-shell</b> - specify which shell program to run (and how) with
the <a href="key.html">keyboard command</a> "!"; if you want to use this, the
respective feature must have been enabled with the <a
href="ctconfig.html">compile-time configuration option</a> OPTION_EXECEXT.
<br>The first parameter must be the absolute path of the shell program you'd
like to use (e.g. /bin/sh or /bin/bash), any further parameters are passed as
command-line options to the shell program without modification.
<br>The "shell" can, in fact, be any program of your choice. If you want to use
a normal shell program, you'll probably want to call it with the parameter "-c"
(because that's what such a shell program needs), so your config file should
contain a line like this: "execext-shell /bin/sh -c".</li>

<li><b>home</b> - the <a href="scheme.html">URL</a> of a document which shall
be displayed when you use the <a href="key.html">keyboard command</a> "h", e.g.
your private home page</li>

<li><b>jumps</b> - URL shortcut associations that are used with the <a
href="key.html">keyboard command</a> "j"; each rule contains a shortcut and the
associated URL. The shortcut may currently be a combination of "almost any"
characters, but you should only use letters and digits; it must not contain
space characters (obviously), and it may be arbitrarily long. The URL may be
either a "constant" URL or a URL pattern. If it is a constant URL and you enter
the shortcut with the keyboard command, retawq simply opens this URL.
<br>If you need something more flexible instead, you can use a URL
<i>pattern</i>. Such a pattern can contain several "markers" of your choice;
after the pattern, you tell retawq which character sequences in the pattern
actually are the markers (separated by single space characters). If you use the
keyboard command then, you don't only enter the shortcut, but also the
arguments which should replace the markers. For example, if you use the
following configuration...
<br><i>jumps<br>&nbsp;visit http://www.!1.org/!2.html !1 !2</i>
<br>...and then enter "visit server document" with the keyboard command, retawq
opens the URL "http://www.server.org/document.html", because the configured
markers "!1" and "!2" are replaced with the entered arguments "server" and
"document", respectively.
<br>You can use almost any sequence of characters as a marker, with a few
exceptions: you can't use space characters because they are interpreted as
argument separators, and the characters "=", ":", ";", ",", "$" and all kinds
of braces and quotation marks are reserved for feature extensions in future
versions. Also you can't use character sequences which might appear in the URL
during the replacement of markers with arguments; so, e.g. you should not use
single letters as markers because they likely appear in the URL. It is
recommended that you only use combinations of exclamation marks and digits as
markers, like in the above example, if possible.</li>

<li><b>keymap</b> - Let certain keys cause certain program actions. Currently,
it is possible to map keys to commands or to line input actions, so you can use
"keymap command" or "keymap line-input" here. Each rule line consists of one
key identifier and one associated action identifier as described in the <a
href="keymap.html">keymaps</a> documentation, e.g. the command map "ctrl-w
menu-windowlist". Your mappings can override retawq's default mappings; for
example, if you configure "ctrl-w document-top", the default command action for
"ctrl-w" ("menu-windowlist") is forgotten.</li>

<li><b>local-dir-sort</b> - By default, retawq sorts the contents of local
directories only by name (ascending). If you want to use a different sorting
<i>occasionally</i>, you can use a "?sort=..." query directly with the URL (cf.
<a href="scheme.html">URL Schemes</a> for an example).
<br>If you want certain directories to be sorted in a special way
<i>regularly</i>, you can simply configure this. Each rule consists of a path
pattern and the desired sorting. The path pattern may be either an exact path
or end with a "*" character (which has the usual meaning). The sorting is given
as a sequence of letters; lowercase letters result in ascending order, the
corresponding uppercase letters in descending order:
<ul><li><i>g</i> - sort by group ID</li>
<li><i>i</i> - sort by name, case-insensitive</li>
<li><i>m</i> - sort by modification time</li>
<li><i>n</i> - sort by name</li>
<li><i>s</i> - sort by size</li>
<li><i>t</i> - sort by type (file/directory/...)</li>
<li><i>u</i> - sort by user ID</li></ul>
As a special case, you can use "_" to disable <i>all</i> sorting for the path
pattern. And the configured sorting can always be overridden by using a
"?sort=..." query directly with the URL.</li>

<li><b>scroll-bars</b> - whether scroll bars shall be shown ("on") or not
("off"); currently this is only relevant if the <a
href="ctconfig.html">compile-time configuration option</a> OPTION_TG has been
set to xcurses</li>

<li><b>search-engine</b> - the <a href="scheme.html">URL</a> of a search engine
form document which shall be displayed when you use the <a
href="key.html">keyboard command</a> "e"</li>

<li><b>termwintitle</b> - whether the terminal window title shall be set (1) or
not (0; default) to a text of the form "retawq <i>version number</i>" in
xterm-like and in GNU <a href="http://www.gnu.org/software/screen/">screen</a>
terminals; this might not work with some terminal emulators; retawq won't try
to reset the title when quitting because finding the original title is
"expensive" and often still fails anyway</li>

</ul></p>

<p><a name="optech"></a><b>Options Part II: Technical</b></p>

<p><ul>

<li><b>ftp-login</b> - Specify the standard username and password for FTP
server login. If you don't provide username and password in a URL (like in
"ftp://user:pass@foo.org/"), retawq uses the words "anonymous" and "guest" for
them by default. But some public FTP servers require that the password is (or
at least looks like) an e-mail address. If you get a "login failed" error
message when trying to access a public FTP service, you should add something
like the following to the configuration file:
<br><i>ftp-login
<br>&nbsp;anonymous mail@foo.org *</i>
<br>Now retawq sends the username "anonymous" and password "mail@foo.org" when
trying to access any ("*") FTP server unless a username and password are
explicitly given in the URL. Of course you can define a more detailed
configuration with several rule lines.
<br>In theory, you could use this configuration for non-public FTP server
access as well. But writing down passwords in clear text is a bad idea, so
don't do it in practice - this configuration option is only intended for
non-standard, public FTP access!</li>

<li><b>ftps-method</b> - (apologies for all this unavoidable technobabble:-)
Several methods exist for protecting FTP transfers with <a
href="tls.html">TLS/SSL</a>; some of these methods are rather historical and
shouldn't be used nowadays, but retawq supports them anyway in order to be as
useful as possible.
<br>For the <a href="scheme.html">URL scheme</a> "ftps", retawq normally tries
to autodetect the appropriate method as follows: if the portnumber is 990 (the
"classical" ftps portnumber), a TLS handshake on a connection is started as
soon as the connection has been established; otherwise retawq tries the FTP
command "AUTH TLS" (plus "PROT P") and fall back to "AUTH SSL" if necessary. If
autodetection finds that a server supports "AUTH TLS" but not "PROT P", it
might ask you something like this: "Server ... can't protect data - allow
cleartext?" If you say yes, "PROT C" is used and <i>the data connection won't
be protected</i>.
<br>However, autodetection might not work with all servers or you might get
tired of answering questions again and again. For example, some servers simply
can't protect the data connection; if this happens to you and you don't mind
transferring the data in the clear (e.g. if you use ftps mainly to avoid
sending the <i>password command</i> in clear text over the control connection),
you can use this option with the method specifier "authtls-dataclear".
<br>Each rule line consists of a host pattern and a method specifier. The host
pattern can either be an exact name or begin with a "*" character (which has
the usual meaning); you can also append a specific portnumber in the usual
"hostname:portnumber" notation; if you don't, the rule applies to all ports on
the host(s). The following method specifiers are available:
<ul>
<li>autodetect: perform autodetection of the appropriate method, as described
above</li>
<li>tls: immediately perform a TLS handshake when the connection has been
established, don't send any "AUTH" command</li>
<li>authtls: start TLS with the FTP command "AUTH TLS", later followed by "PROT
P"</li>
<li>authtls-dataclear: start TLS with the FTP command "AUTH TLS", later
followed by "PROT C", so <i>the data connection won't be protected</i> with
this method</li>
<li>authssl: start TLS with the FTP command "AUTH SSL"</li>
</ul>
<!-- information about outdated methods taken from the nowadays also outdated
draft-murray-auth-ftp-ssl-06.txt, sections 4., 7. and 9. -->
</li>

<li><b>http-cookies</b> - If the <a href="ctconfig.html">compile-time
configuration option</a> OPTION_COOKIES has been enabled, you can specify for
which HTTP servers cookies may actually be stored and sent (default: none are
stored/sent); cookies are only stored in RAM, not written to a file, so they
are automatically discarded when you quit retawq. The first argument in each
rule must be either "allow" or "deny". The second argument is a host name
pattern which can be either an exact name or begin with a "*" character (which
has the usual meaning).</li>

<li><b>http-proxies</b> - By default, retawq doesn't use any proxies when
sending HTTP requests to servers. But in some local networks, the connection to
the Internet is only possible via proxies, e.g. because your local network is
protected by a firewall.
<br>To define HTTP proxies, you start a "http-proxies" section in the config
file and define one rule per subsection line; each rule consists of a proxy and
a host pattern, optionally followed by a username and a password for proxy
authentication. (The password is entered in clear text, which might be a
security problem, so you should make sure that nobody but you can read the
config file; for example, use the shell command "chmod go-rwx config" in
advance.) Technobabble: proxy authentication can only apply basic
authentication, not yet digest authentication.
<br>You can also provide portnumbers in the usual "name:portnumber" notation;
if you don't provide a portnumber for the proxy, port 8080 is used; if you
don't provide a portnumber for the host pattern, the given rule applies to
<i>all</i> host ports. A host pattern can either be an exact name or begin with
a "*" character (which has the usual meaning).
<br>For the example of a local network behind a firewall, your configuration
might contain something like this:
<br><i>http-proxies:
<br>&nbsp;none *my-domain.org
<br>&nbsp;firewall.my-domain.org *</i>
<br>This means that all servers of your own domain (that is "inside the local
network" for this example) are accessed without proxies (use "none" as the
proxy name), and all other servers are contacted via the proxy
"firewall.my-domain.org".</li>

<li><b>http-version</b> - Too many HTTP server implementations don't handle the
HTTP/1.1 protocol correctly, so retawq uses HTTP/1.0 by default nowadays. If
you'd like to try HTTP/1.1 anyway, this option allows you to set an explicit
HTTP protocol version. Each rule consists of a host pattern and a version
number. The host pattern can either be an exact name or begin with a "*"
character (which has the usual meaning); you can also append a specific
portnumber in the usual "hostname:portnumber" notation; if you don't, the rule
applies to all ports on the host(s). The protocol version number can currently
be either "1.0" or "1.1". In general, this option applies to both HTTP and
https; you can easily restrict it to only one of these by providing a
portnumber (usually 80 for HTTP and 443 for https) with the host pattern.</li>

<li><b>https-cookies</b> - This is used for the <a href="scheme.html">URL
scheme</a> "https" like "http-cookies" is used for "http".</li>

<li><b>https-proxies</b> - This is used for the <a href="scheme.html">URL
scheme</a> "https" like "http-proxies" is used for "http".</li>

<li><b>languages</b> - a comma-separated, whitespace-free list of language
codes for your preferred natural languages in which you would like to receive
documents from HTTP servers; example: "fr,en" if you prefer French documents
but also accept :-) English documents. If the server can't satisfy your
preference, it sends the document in "any" language, most likely English. - The
default value for this option is "en" (i.e., English documents are preferred,
nothing else is said). - Technobabble: this option corresponds to the HTTP
header "Accept-Language".</li>

<li><b>local-cgi</b> - If the <a href="ctconfig.html">compile-time
configuration option</a> OPTION_LOCAL_CGI has been enabled, you can specify
which CGI scripts on the local computer may be executed with the <a
href="scheme.html">URL scheme</a> "local-cgi" (default: nothing allowed). The
first argument in each rule must be either "allow" or "deny". The second
argument is a script path pattern which must begin with a "/" character and may
be either an exact script name or end with a "*" character (which has the usual
meaning).</li>

<li><b>news-server-default</b> - the default server for "news:" and "nntp:" <a
href="scheme.html">URLs</a> which don't contain an explicit server name</li>

<li><b>redirections</b> - maximum number of automatic URL redirections with the
HTTP and https protocols; the default is 10 (which should be enough for any
"real-life" case), allowed values are in the range 3..20.</li>

<li><b>user-agent</b> - most browsers identify themselves to HTTP servers by
including a "User-Agent" line in the HTTP header. The "user-agent" option
allows you to specify how much information about your computer retawq may
reveal to servers. The amount of information is defined by a number ranging
from 0 to 3, which had the following effect on <i>my</i> computer:
<br><ul>
<li>"user-agent 0" - "User-Agent: retawq/0.0.1 [en] (text)"</li>
<li>"user-agent 1" - "User-Agent: retawq/0.0.1 [en] (text; Linux)"</li>
<li>"user-agent 2" - "User-Agent: retawq/0.0.1 [en] (text; Linux 2.2.19)"</li>
<li>"user-agent 3" - "User-Agent: retawq/0.0.1 [en] (text; Linux 2.2.19;
i686)"</li></ul>
The resulting HTTP header line contains the program name ("retawq"), the
version number (here "0.0.1"), the language code for the default user interface
language (here "[en]" for the English language) and some additional information
in parentheses, e.g. the word "text" which is there to distinguish the
currently used text mode from the not-yet-implemented graphics mode.
Distinguishing text and graphics mode might help dynamic content creation
programs (CGI scripts) on servers to decide whether they should generate a
fully-blown graphics version of some document or a lightweight text-only
version.
<br>Higher numbers for the option "user-agent" result in more information. If
you want to advertise your operating system (like me:-), you should set the
number to at least 1. The default value is 0, of course, so that you don't
reveal private information accidentally.
<br>Technobabble: the information is obtained via the operating system function
"uname()". If you're curious, you can easily find out this information for your
computer with the command-line program "uname", e.g. "uname -srm" or "uname
-a".</li>

</ul></p>

<p><hr>This documentation file is part of version 0.2.6c of <a
href="http://retawq.sourceforge.net/">retawq</a>, a network client created by
<span lang="de">Arne Thoma&szlig;en</span>. retawq is basically released under
certain versions of the GNU General Public License and WITHOUT ANY WARRANTY.
Copyright (C) 2001-2006 <a href="mailto:arne@arne-thomassen.de"><span
lang="de">Arne Thoma&szlig;en</span></a>.</p>
</body></html>
